Node / mirrors / RTNode-HeltecV4 rns://f53941ecdb23472c4af67042474c7918/mirrors/RTNode-HeltecV4

Mirrored from https://github.com/jrl290/RTNode-HeltecV4 synced 11h ago

󰉖 Files • 󱌣 Work (0) • 󰋚 Commits (129) • 󰘬 Branches (2) • 󰓼 Tags (41) • 󰋑 Thanks (0) •  Stats

All published firmware releases should be treated as Beta unless a release is explicitly called stable. In practice, that means they are lightly tested and aimed at early adopters who can validate on real hardware.

For tooling compatibility, version tags can stay numeric (for example T383838v1.0.30), but user-facing release labels in docs, flash tools, and release titles should include Beta.

T282828

Built on microReticulum (a C++ port of the Reticulum network stack) and the RNode firmware by Mark Qvist.

• Bidirectional LoRa ↔ TCP bridging — local LoRa mesh nodes can reach the global Reticulum backbone and vice versa

• Web-based configuration portal — WiFi SSID/password, backbone host/port, LoRa parameters, all configurable via captive portal

• OLED status display — real-time status indicators for LoRa, WiFi, WAN (backbone), LAN (local TCP), plus IP address, port, and airtime

• Optional local TCP server — serve local devices on your WiFi in addition to the backbone connection

• Automatic reconnection — WiFi and TCP connections recover from drops with exponential backoff

• ESP32 memory-optimized — table sizes, timeouts, and caching tuned for the constrained MCU environment

• Dual board support — supports both Heltec V3 (8MB flash) and V4 (16MB flash, 2MB PSRAM) with automatic board and PSRAM detection

This firmware was designed for the Heltec WiFi LoRa 32 V4. This board was chosen for its 2MB PSRAM and LoRa capabilities. While the V3 is supported, it uses the ESP32-S3FN8 which has no PSRAM. The firmware detects PSRAM at runtime and allocates the TLSF memory pool from SPIRAM when available, falling back to internal SRAM (~170 KB) on boards without PSRAM.

The Heltec V4 has two board revisions that use different front-end modules. The firmware auto-detects the FEM type at boot:

A single T383838rtnode_heltec_v4 binary runs correctly on both revisions.

Open jrl290.github.io/RTNode-HeltecV4 in Chrome or Edge, connect your RTNode via USB, and follow the two-step flow:

1. Detect — click Detect and select your device from the browser's serial port picker. The flasher identifies the board (V3 or V4) automatically using PSRAM detection.

2. Flash — choose Update firmware (app only, settings preserved) or Full install (erases everything — use for first-time installs), then click Flash Firmware.

The web flasher presents all published firmware versions as Beta so the light-testing status is visible at selection time.

│ Web Serial requires Chrome 89+ or Microsoft Edge. Firefox and Safari are not supported. On Linux,

│ add your user to the T383838dialout group first: T383838sudo usermod -a -G dialout $USER (then log out and back

│ in).

The easiest way to flash from the command line. You only need Python 3 and a USB cable.

T282828

By default, T383838flash.py uses the bundled T383838Release/esptool/esptool.py for reproducible flashing and labels fetched GitHub firmware as Beta. Only use T383838--use-system-esptool if you explicitly want to override that with a host-installed esptool.

The flash utility auto-detects whether a V3 or V4 is connected by querying the flash size (8MB = V3, 16MB = V4). You can override with T383838--board v3 or T383838--board v4. It will list all available serial ports and prompt you to choose one. If no ports are detected, you may need to hold the BOOT button while pressing RESET to enter download mode.

For development or customization:

T282828

If you have the merged binary (T383838rtnode_heltec_v4.bin), you can flash it with a single esptool command:

T282828

Replace T383838/dev/ttyACM0 with your serial port (T383838/dev/cu.usbmodem* on macOS, T383838COM3 on Windows).

On first boot (or if no configuration is found), the device automatically enters the Configuration Portal.

The config portal activates automatically on:

• First boot — when no saved configuration exists

• Button hold >5 seconds — hold the PRG button for 5+ seconds, the device reboots into config mode

When active, the device creates a WiFi access point named T383838RNode-Boundary-Setup (open network). A captive portal should appear automatically when you connect; if not, browse to T383838http://192.168.4.1.

The web form has four sections:

Optional: announce this node and its parameters on the Reticulum network so external maps such as rmap.world can automatically place a pin for it. Disabled by default — only enable if you want this node to be publicly listed.

When enabled, the firmware periodically (~every 6 hours, matching the Reticulum default) emits an interface-discovery announce as described in the Reticulum manual. The announce is sent on the destination T383838rnstransport.discovery.interface and contains:

• Interface type (T383838RNodeInterface) and the node's transport-identity hash

• Discovery name (T383838RTNode-<short-hash>)

• Latitude, longitude and height (decimal degrees / metres)

• Operating LoRa parameters (frequency, bandwidth, spreading factor, coding rate)

• IFAC network name and key, when configured

The payload is sealed with an LXMF proof-of-work stamp (cost 14, matching T383838RNS/Discovery.py's T383838DEFAULT_STAMP_VALUE), and the resulting stamp is cached so the proof-of-work only re-runs when the advertised parameters change.

After saving, the device reboots with the new configuration applied.

The 128×64 OLED is split into two panels:

T282828

• Filled circle (●) = active/connected

• Unfilled circle (○) = inactive/disconnected

• Labels are UPPERCASE when active, lowercase when inactive (except LAN which is always uppercase)

• LAN row is hidden when the Local TCP Server is disabled in configuration — the remaining layout stays in place

T282828

• Port shows the Local TCP server port (the port local nodes connect to), not the backbone port

• Port line is hidden when the Local TCP Server is disabled

The firmware runs up to three RNS interfaces simultaneously, using different interface modes to control announce propagation and routing behavior:

Always uses T383838MODE_GATEWAY. Announce broadcasts propagate freely in both directions, allowing the relay to forward announces between LoRa nodes and ensuring Transport's own path-probe packets are transmitted.

The TCP backbone connection uses T383838MODE_BOUNDARY (T3838380x20), a custom transport mode adapted for the memory-constrained ESP32 environment. In this mode:

• Incoming announces from the backbone are received and cached, but not stored in the path table by default — only stored when specifically requested via a path request from a local LoRa node

• This prevents the path table (limited to 24 entries on ESP32) from being overwhelmed by thousands of backbone destinations

• When the path table needs to be culled, backbone-learned paths are evicted first, preserving locally-needed LoRa paths

Only registered when WiFi is enabled and T383838tcp_mode == 1 (client mode).

When both WiFi and the local TCP server are enabled, a TCP server on the WiFi network allows local Reticulum nodes to connect. It uses T383838MODE_GATEWAY, so announces are forwarded freely to and from local TCP clients (matching standard Reticulum transport node behaviour). Also registered as a local-client interface so Transport forwards announces, link packets, and proofs to connected clients.

Local TCP clients should be endpoint clients, not transport routers. If an application such as Meshchat is configured with Reticulum transport mode enabled, it can relay WAN-scale traffic into RTNode through the LAN side, even when RTNode's own WAN/backbone interface is disabled. That defeats the boundary model and can fill routing/cache state from the trusted side. Disable transport mode on Meshchat/Reticulum clients connected to the Local TCP Server unless you are intentionally testing bounded LAN-side transport behavior.

• Each TCP interface must have a unique name to produce a unique interface hash — the backbone uses T383838"TcpInterface" and the local server uses T383838"LocalTcpInterface". Without distinct names, both interfaces produce the same hash, causing the interface map lookup to fail when routing packets.

• TCP interfaces are configured with a 10 Mbps bitrate, which causes Reticulum's Transport to prefer TCP paths over LoRa paths (typically ~1–10 kbps) when both are available for the same destination.

• When the Local TCP Server is disabled, its status indicator (LAN) and port number are hidden from the OLED display.

The ESP32-S3 has limited RAM compared to a desktop Reticulum node. Several customizations were made to the microReticulum library to operate reliably within these constraints:

The most critical optimization: backbone announces are not stored in the path table by default. A backbone like T383838rmap.world may advertise hundreds of destinations. Storing them all would evict every local LoRa path.

Instead:

1. Backbone announces are received and their packets cached to flash storage

2. When a local LoRa node requests a path, the transport node checks its cache and responds directly

3. Only specifically requested paths get a path table entry

4. Path table culling prioritizes evicting backbone entries over local ones

When a transport-addressed packet arrives from LoRa but the transport node has no path table entry for it, the firmware:

1. Strips the transport headers (converts T383838HEADER_2 → T383838HEADER_1/BROADCAST)

2. Forwards the raw packet to the backbone interface

3. Creates reverse-table entries so proofs can route back to the sender

This acts as a default route — any packet the transport node can't route locally gets forwarded to the backbone.

The original microReticulum T383838get_cached_packet() function called T383838update_hash() after deserializing cached packets from flash. However, T383838update_hash() only computes the packet hash — it does not parse the raw bytes into fields like T383838destination_hash, T383838data, T383838flags, etc.

This was changed to call T383838unpack() instead, which parses all packet fields AND computes the hash. Without this fix, path responses contained empty destination hashes and were silently dropped by LoRa nodes.

│ Note: T383838unpack() only parses the plaintext routing envelope (destination hash, flags, hops,

│ transport headers). It does not decrypt the end-to-end encrypted payload. Every Reticulum

│ transport node performs equivalent header parsing during normal routing — this is standard

│ behavior, not a security concern.

The C++ T383838std::map::insert() method silently does nothing when a key already exists — unlike Python's T383838dict[key] = value which replaces. The original microReticulum code used T383838insert() to update path table entries, meaning stale LoRa paths were never replaced by newer TCP paths (or vice versa).

This was fixed by calling T383838erase() before T383838insert(), ensuring updated path entries always replace stale ones. Without this fix, the transport node would continue routing packets via an old interface even after a better path was learned.

Each RNS interface must have a unique name because the name is hashed to produce the interface identifier used in path table lookups. If two interfaces share the same name, they produce the same hash, and T383838std::map can only store one — causing the Transport layer to fail to resolve the correct outbound interface for packets.

The TcpInterface constructor accepts an explicit T383838name parameter: the backbone uses T383838"TcpInterface" and the local server uses T383838"LocalTcpInterface".

In the configuration portal:

1. Set WiFi SSID and password

2. Set TCP Backbone Mode to Client

3. Set Backbone Host to T383838rmap.world

4. Set Backbone Port to T3838384242

5. Save and reboot

On your server, configure T383838rnsd with a TCP Server Interface in T383838~/.reticulum/config:

T282828

Then configure the transport node as a Client pointing to your server's IP.

On your server, configure T383838rnsd with a TCP Client Interface:

T282828

Set the transport node's Local TCP Server to Enabled (port 4242).

The firmware depends on microReticulum T3838380.2.4, automatically fetched by PlatformIO on first build. After the first build, the library sources under T383838.pio/libdeps/rtnode_heltec_v4/microReticulum/src/ need the patches described in "Routing & Memory Customizations" above. Key files modified:

This project is licensed under the GNU General Public License v3.0 — see LICENSE for details.

Based on:

• RNode Firmware by Mark Qvist (GPL-3.0)

• microReticulum by Chris Attermann (GPL-3.0)

• Reticulum by Mark Qvist (MIT)